---
title: Workload Entry
description: Configuration affecting VMs onboarded into the mesh.
location: https://istio.io/docs/reference/config/networking/workload-entry.html
layout: protoc-gen-docs
generator: protoc-gen-docs
schema: istio.networking.v1alpha3.WorkloadEntry
aliases: [/docs/reference/config/networking/v1alpha3/workload-entry]
number_of_entries: 1
---
<p><code>WorkloadEntry</code> enables operators to describe the properties of a
single non-Kubernetes workload such as a VM or a bare metal server
as it is onboarded into the mesh. A <code>WorkloadEntry</code> must be
accompanied by an Istio <code>ServiceEntry</code> that selects the workload
through the appropriate labels and provides the service definition
for a <code>MESH_INTERNAL</code> service (hostnames, port properties, etc.). A
<code>ServiceEntry</code> object can select multiple workload entries as well
as Kubernetes pods based on the label selector specified in the
service entry.</p>

<p>When a workload connects to <code>istiod</code>, the status field in the
custom resource will be updated to indicate the health of the
workload along with other details, similar to how Kubernetes
updates the status of a pod.</p>

<p>The following example declares a workload entry representing a VM
for the <code>details.bookinfo.com</code> service. This VM has sidecar
installed and bootstrapped using the <code>details-legacy</code> service
account. The service is exposed on port 80 to applications in the
mesh. The HTTP traffic to this service is wrapped in Istio mutual
TLS and sent to sidecars on VMs on target port 8080, that in turn
forward it to the application on localhost on the same port.</p>

<p>{{<tabset category-name="example">}}
{{<tab name="v1alpha3" category-value="v1alpha3">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: WorkloadEntry
metadata:
  name: details-svc
spec:
  # use of the service account indicates that the workload has a
  # sidecar proxy bootstrapped with this service account. Pods with
  # sidecars will automatically communicate with the workload using
  # istio mutual TLS.
  serviceAccount: details-legacy
  address: 2.2.2.2
  labels:
    app: details-legacy
    instance-id: vm1
</code></pre>

<p>{{</tab>}}</p>

<p>{{<tab name="v1beta1" category-value="v1beta1">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1beta1
kind: WorkloadEntry
metadata:
  name: details-svc
spec:
  # use of the service account indicates that the workload has a
  # sidecar proxy bootstrapped with this service account. Pods with
  # sidecars will automatically communicate with the workload using
  # istio mutual TLS.
  serviceAccount: details-legacy
  address: 2.2.2.2
  labels:
    app: details-legacy
    instance-id: vm1
</code></pre>

<p>{{</tab>}}
{{</tabset>}}</p>

<p>and the associated service entry</p>

<p>{{<tabset category-name="example">}}
{{<tab name="v1alpha3" category-value="v1alpha3">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: details-svc
spec:
  hosts:
  - details.bookinfo.com
  location: MESH_INTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
    targetPort: 8080
  resolution: STATIC
  workloadSelector:
    labels:
      app: details-legacy
</code></pre>

<p>{{</tab>}}</p>

<p>{{<tab name="v1beta1" category-value="v1beta1">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: details-svc
spec:
  hosts:
  - details.bookinfo.com
  location: MESH_INTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
    targetPort: 8080
  resolution: STATIC
  workloadSelector:
    labels:
      app: details-legacy
</code></pre>

<p>{{</tab>}}
{{</tabset>}}</p>

<p>The following example declares the same VM workload using
its fully qualified DNS name. The service entry&rsquo;s resolution
mode should be changed to DNS to indicate that the client-side
sidecars should dynamically resolve the DNS name at runtime before
forwarding the request.</p>

<p>{{<tabset category-name="example">}}
{{<tab name="v1alpha3" category-value="v1alpha3">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: WorkloadEntry
metadata:
  name: details-svc
spec:
  # use of the service account indicates that the workload has a
  # sidecar proxy bootstrapped with this service account. Pods with
  # sidecars will automatically communicate with the workload using
  # istio mutual TLS.
  serviceAccount: details-legacy
  address: vm1.vpc01.corp.net
  labels:
    app: details-legacy
    instance-id: vm1
</code></pre>

<p>{{</tab>}}</p>

<p>{{<tab name="v1beta1" category-value="v1beta1">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1beta1
kind: WorkloadEntry
metadata:
  name: details-svc
spec:
  # use of the service account indicates that the workload has a
  # sidecar proxy bootstrapped with this service account. Pods with
  # sidecars will automatically communicate with the workload using
  # istio mutual TLS.
  serviceAccount: details-legacy
  address: vm1.vpc01.corp.net
  labels:
    app: details-legacy
    instance-id: vm1
</code></pre>

<p>{{</tab>}}
{{</tabset>}}</p>

<p>and the associated service entry</p>

<p>{{<tabset category-name="example">}}
{{<tab name="v1alpha3" category-value="v1alpha3">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: details-svc
spec:
  hosts:
  - details.bookinfo.com
  location: MESH_INTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
    targetPort: 8080
  resolution: DNS
  workloadSelector:
    labels:
      app: details-legacy
</code></pre>

<p>{{</tab>}}</p>

<p>{{<tab name="v1beta1" category-value="v1beta1">}}</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: details-svc
spec:
  hosts:
  - details.bookinfo.com
  location: MESH_INTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
    targetPort: 8080
  resolution: DNS
  workloadSelector:
    labels:
      app: details-legacy
</code></pre>

<p>{{</tab>}}
{{</tabset>}}</p>

<h2 id="WorkloadEntry">WorkloadEntry</h2>
<section>
<p>WorkloadEntry enables specifying the properties of a single non-Kubernetes workload such a VM or a bare metal services that can be referred to by service entries.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="WorkloadEntry-address">
<td><code>address</code></td>
<td><code>string</code></td>
<td>
<p>Address associated with the network endpoint without the
port.  Domain names can be used if and only if the resolution is set
to DNS, and must be fully-qualified without wildcards. Use the form
unix:///absolute/path/to/socket for Unix domain socket endpoints.</p>

</td>
<td>
Yes
</td>
</tr>
<tr id="WorkloadEntry-ports">
<td><code>ports</code></td>
<td><code>map&lt;string,&nbsp;uint32&gt;</code></td>
<td>
<p>Set of ports associated with the endpoint. If the port map is
specified, it must be a map of servicePortName to this endpoint&rsquo;s
port, such that traffic to the service port will be forwarded to
the endpoint port that maps to the service&rsquo;s portName. If
omitted, and the targetPort is specified as part of the service&rsquo;s
port specification, traffic to the service port will be forwarded
to one of the endpoints on the specified <code>targetPort</code>. If both
the targetPort and endpoint&rsquo;s port map are not specified, traffic
to a service port will be forwarded to one of the endpoints on
the same port.</p>

<p><strong>NOTE 1:</strong> Do not use for <code>unix://</code> addresses.</p>

<p><strong>NOTE 2:</strong> endpoint port map takes precedence over targetPort.</p>

</td>
<td>
No
</td>
</tr>
<tr id="WorkloadEntry-labels">
<td><code>labels</code></td>
<td><code>map&lt;string,&nbsp;string&gt;</code></td>
<td>
<p>One or more labels associated with the endpoint.</p>

</td>
<td>
No
</td>
</tr>
<tr id="WorkloadEntry-network">
<td><code>network</code></td>
<td><code>string</code></td>
<td>
<p>Network enables Istio to group endpoints resident in the same L3
domain/network. All endpoints in the same network are assumed to be
directly reachable from one another. When endpoints in different
networks cannot reach each other directly, an Istio Gateway can be
used to establish connectivity (usually using the
<code>AUTO_PASSTHROUGH</code> mode in a Gateway Server). This is
an advanced configuration used typically for spanning an Istio mesh
over multiple clusters.</p>

</td>
<td>
No
</td>
</tr>
<tr id="WorkloadEntry-locality">
<td><code>locality</code></td>
<td><code>string</code></td>
<td>
<p>The locality associated with the endpoint. A locality corresponds
to a failure domain (e.g., country/region/zone). Arbitrary failure
domain hierarchies can be represented by separating each
encapsulating failure domain by /. For example, the locality of an
an endpoint in US, in US-East-1 region, within availability zone
az-1, in data center rack r11 can be represented as
us/us-east-1/az-1/r11. Istio will configure the sidecar to route to
endpoints within the same locality as the sidecar. If none of the
endpoints in the locality are available, endpoints parent locality
(but within the same network ID) will be chosen. For example, if
there are two endpoints in same network (networkID &ldquo;n1&rdquo;), say e1
with locality us/us-east-1/az-1/r11 and e2 with locality
us/us-east-1/az-2/r12, a sidecar from us/us-east-1/az-1/r11 locality
will prefer e1 from the same locality over e2 from a different
locality. Endpoint e2 could be the IP associated with a gateway
(that bridges networks n1 and n2), or the IP associated with a
standard service endpoint.</p>

</td>
<td>
No
</td>
</tr>
<tr id="WorkloadEntry-weight">
<td><code>weight</code></td>
<td><code>uint32</code></td>
<td>
<p>The load balancing weight associated with the endpoint. Endpoints
with higher weights will receive proportionally higher traffic.</p>

</td>
<td>
No
</td>
</tr>
<tr id="WorkloadEntry-service_account">
<td><code>serviceAccount</code></td>
<td><code>string</code></td>
<td>
<p>The service account associated with the workload if a sidecar
is present in the workload. The service account must be present
in the same namespace as the configuration ( WorkloadEntry or a
ServiceEntry)</p>

</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
